<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:x="https://www.texmacs.org/2002/extensions" xmlns:m="http://www.w3.org/1998/Math/MathML">
  <head>
    <title>TeXmacs notes</title>
    <meta content="TeXmacs 1.99.15" name="generator"></meta>
    <link href="../resources/notes-base.css" type="text/css" rel="stylesheet"></link>
    <link href="../resources/blog-icon.png" rel="icon"></link>
    <script src="../resources/highlight.pack.js" language="javascript" defer></script>
    <script src="../resources/notes-base.js" language="javascript" defer></script>
  </head>
  <body>
    <div class="notes-header">
      <p>
        <img class="image" src="../resources/texmacs-blog-transparent.png" width="28.116784"></img><span style="margin-left: 2pt"></span><a href="./main.html">[main]</a><em
        class="notes-header-name">Notes on TeXmacs</em>
      </p>
    </div>
    <h1 id="auto-1">Contribution guide<span style="margin-left: 1em"></span></h1>
    <p>
      The blog can be read offline within TeXmacs. Just open one of the
      documents in the source directory and click on the links: they point to
      the local .tm files. Browse back-forward with the buttons <img class="image"
      src="../resources/contribution-guide/tm_back.png" height="25.3051056" width="25.3051056"></img> and <img class="image" src="../resources/contribution-guide/tm_forward.png" height="25.3051056" width="25.3051056"></img> on
      the top toolbar.
    </p>
    <p>
      Typically it should just be necessary to modify or add to only the
      <code>.tm</code> sources in the <code>src/</code> directory&mdash;and
      modify accordingly <a href="./main.tm">main.tm</a>. The html files are then
      generated by one of the maintainers after the pull request is merged
      (hopefully this will be automated in the near future): for this reason,
      please do not add the locally-generated web pages (see below) to the git
      commits. Once the changes are pulled in they will become immediately
      publicly visible on the website.
    </p>
    <p>
      To automatically regenerate all the web pages use <class class="tmweb-menu" style="font-family: sans-serif">Tools</class>&rarr;<class
      class="tmweb-menu" style="font-family: sans-serif">Web</class>&rarr;<class class="tmweb-menu" style="font-family: sans-serif">Create/Update web
      site</class><a id="auto-2"></a> within TeXmacs and choose <code>src/</code> as
      source and <code>docs/</code> as destination directories. In this case,
      all links will become links to the local versions of the document and
      you will be able to browse them locally using a web-browser (as said
      above, the maintainers are going to take care of the conversion to html
      in the web site).
    </p>
    <p>
      This <a href="./template.html">template file</a> can be used for new articles.
    </p>
    <p>
      If you do not have commit rights (that is, write permission) on the
      repository, you can make a pull request starting from a fork of the
      repository.
    </p>
    <p>
      It is necessary to perform a few actions using the terminal. The
      sequence is
      fork&ndash;clone&ndash;modify&ndash;add&ndash;commit&ndash;push and
      finally make a pull request. People that use <class style="font-variant: small-caps">Git</class>
      are familiar with these commands. Here are some hints for those that are
      using <class style="font-variant: small-caps">Git</class> for the first time. A basic tutorial on
      how to work on one's own repositories using <class style="font-variant: small-caps">Git</class> is
      available at
    </p>
    <p>
      <a href="https://www.earthdatascience.org/workshops/intro-version-control-git/basic-git-commands/">https://www.earthdatascience.org/workshops/intro-version-control-git/basic-git-commands/</a>
    </p>
    <ol>
      <li>
        <p>
          Fork the repository at <class style="font-variant: small-caps">Github</class>. This can be
          done through the web interface there. You need to have a <class
          style="font-variant: small-caps">Github</class> account. This operation creates a complete
          copy of the main repository in your <class style="font-variant: small-caps">Github</class>
          account.
        </p>
      </li>
      <li>
        <p>
          Clone it locally. Within a suitable directory execute the command
        </p>
        <div class="tmweb-code">
          <pre class="verbatim" xml:space="preserve">
git clone https://github.com/texmacs/notes.git</pre>
        </div>
        <p>
          a subdirectory named <code>notes</code> will appear, where you will
          be able to work on the files. Now you have a complete copy of the
          main repository on your computer. You can browse the site also
          locally by pointing the browser to <tt>index.html</tt>.
        </p>
      </li>
      <li>
        <p>
          Make your modifications locally.
        </p>
      </li>
      <li>
        <p>
          Add the modified files to git (command <code>git add</code>).
        </p>
      </li>
      <li>
        <p>
          Commit with <code>git commit</code>
        </p>
        <ul>
          <li>
            <p>
              the first time you do this, git might ask you to set your
              identity with the commands
            </p>
            <div class="tmweb-code">
              <pre class="verbatim" xml:space="preserve">
git config --global user.email</pre>
            </div>
            <p>
              and
            </p>
            <div class="tmweb-code">
              <pre class="verbatim" xml:space="preserve">
git config --global user.name</pre>
            </div>
            <p>
              the <code>&ndash;global</code> switch can be omitted; in this
              case the identity will be set for the current repository only.
            </p>
          </li>
        </ul>
      </li>
      <li>
        <p>
          Push the modifications to your forked repository using <code>git
          push</code>. <class style="font-variant: small-caps">Git</class> might then ask for username
          and password.
        </p>
      </li>
      <li>
        <p>
          Now you can make a pull request through the web interface, at
        </p>
        <p>
          <a href="https://github.com/texmacs/notes/pulls">https://github.com/texmacs/notes/pulls</a>
        </p>
        <p>
          (green button <code>New pull request</code>). The web interface
          gives further helpful hints. Follow the link <code>compare across
          forks</code> above the pulldown menus to have them show forks, from
          which you can select yours.
        </p>
      </li>
      <li>
        <p>
          The pull request on github asks the maintainers to integrate your
          changes into the public repository.
        </p>
      </li>
      <li>
        <p>
          Go to step 3.
        </p>
      </li>
    </ol>
    <p>
      <strong>To keep your fork up to date:</strong>
    </p>
    <ol>
      <li>
        <p>
          Configure the upstream remote repository with
        </p>
        <div class="tmweb-code">
          <pre class="verbatim" xml:space="preserve">
git remote add upstream https://github.com/texmacs/notes.git</pre>
        </div>
        <p>
          Detailed instructions at:
        </p>
        <p>
          <a href="https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork">https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork</a>
        </p>
      </li>
      <li>
        <p>
          Follow the steps at 
        </p>
        <p>
          <a href="https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork">https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork</a>
        </p>
        <p>
          that is:
        </p>
        <ul>
          <li>
            <p>
              Make sure you are working on the branch you want to work on,
              e.g.
            </p>
            <div class="tmweb-code">
              <pre class="verbatim" xml:space="preserve">
git checkout main</pre>
            </div>
            <p>
              where git might answer you
            </p>
            <div class="tmweb-code">
              <pre class="verbatim" xml:space="preserve">
Already on 'main'
Your branch is up to date with 'origin/main'.</pre>
            </div>
          </li>
          <li>
            <p>
              Then do
            </p>
            <div class="tmweb-code">
              <pre class="verbatim" xml:space="preserve">
<code>git fetch upstream</code>
<code>git merge upstream/main</code>
<code>git push</code></pre>
            </div>
          </li>
        </ul>
        <p>
          
        </p>
      </li>
    </ol>
    <p>
      Please check also the <a href="editorial-guidelines.html">editorial guidelines</a> for preparing
      your content.
    </p>
  </body>
</html>